{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# hvPlot.points\n",
    "\n",
    "```{eval-rst}\n",
    ".. currentmodule:: hvplot\n",
    "\n",
    ".. automethod:: hvPlot.points\n",
    "```\n",
    "\n",
    "## Backend-specific styling options\n",
    "\n",
    "```{eval-rst}\n",
    ".. backend-styling-options:: points\n",
    "```\n",
    "\n",
    "## Examples\n",
    "\n",
    "### Basic points plot\n",
    "\n",
    "This example shows how to create a simple points plot."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "import pandas as pd\n",
    "\n",
    "df = pd.DataFrame({\"x\": [0, 1, 2, 3], \"y\": [0, 1, 4, 9]})\n",
    "\n",
    "df.hvplot.points(x=\"x\", y=\"y\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's use a more realistic dataset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = hvplot.sampledata.earthquakes(\"pandas\")\n",
    "\n",
    "df.hvplot.points(x='lon', y='lat', title='Earthquakes location')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Grouping by categories\n",
    "\n",
    "To distinguish categories visually, you can use the `by` parameter. This automatically colors points based on the specified column."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = hvplot.sampledata.earthquakes(\"pandas\")\n",
    "\n",
    "df.hvplot.points(\n",
    "    x='lon', y='lat', marker='s',\n",
    "    by=['depth_class', 'mag_class'], title='Points plot colored by depth and magnitude classes',\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Grouping by categories\n",
    "\n",
    "To distinguish categories visually, you can use the `by` parameter. This automatically colors points based on the specified column(s). The generated plot is a [HoloViews NdOverlay](https://holoviews.org/reference/containers/bokeh/NdOverlay.html)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = hvplot.sampledata.earthquakes(\"pandas\")\n",
    "\n",
    "df.hvplot.points(\n",
    "    x='lon', y='lat', by=['depth_class', 'mag_class'],\n",
    "    title='Points plot grouped by depth and magnitude classes with \"by\"',\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ":::{note}\n",
    "If your goal is to simply color the plot by a given categorical variable, then you can use the [`color`](option-color) option instead of [`by`](option-by). The former will vectorize the color styling (i.e., each marker has its own color) while the latter will generate an overlay of points plots. As a consequence, using `color` is much more efficient in this case.\n",
    ":::"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = hvplot.sampledata.earthquakes(\"pandas\")\n",
    "\n",
    "df.hvplot.points(\n",
    "    x='lon', y='lat', color='depth_class',\n",
    "    title='Points plot colored by depth class with \"color\"',\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Control marker style\n",
    "\n",
    "The `marker` keyword can be used to control the markers style, see the [`scatter` reference page](scatter-marker-style) for more information."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Control color and size\n",
    "\n",
    "You can also vary marker size with the `s` option and color with `c` (or `color`) using numeric columns."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = hvplot.sampledata.earthquakes(\"pandas\")\n",
    "\n",
    "df.hvplot.points(\n",
    "    x=\"lon\", y=\"lat\", c=\"mag\", s=\"depth\", cmap=\"inferno_r\",\n",
    "    clabel=\"Magnitude values\", title=\"Earthquake depth (color by magnitude)\",\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Scatter plot with scaling and logarithmic color mapping\n",
    "\n",
    "This example shows how to fine-tune scatter plots by scaling point sizes and applying a logarithmic color scale. Note we set the `scale` option to uniformally increase the marker size by a factor of 3."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "import hvplot.pandas  # noqa\n",
    "import numpy as np\n",
    "\n",
    "df = pd.DataFrame({\n",
    "    'x': np.random.rand(100) * 10,\n",
    "    'y': np.random.rand(100) * 10,\n",
    "    'size': np.random.rand(100) * 100 + 10,\n",
    "    'intensity': np.random.lognormal(mean=2, sigma=1, size=100)\n",
    "})\n",
    "\n",
    "df.hvplot.points(\n",
    "    x='x', y='y', s='size', scale=3,\n",
    "    c='intensity', cmap='Blues', logz=True,\n",
    "    title='Points plot with size scaling and log color'\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Geographic plot\n",
    "\n",
    "`points` plots are 2D plots and well suited for displaying maps. In this example we set `geo=True` to enable plotting with GeoViews and `tiles=True` to overlay the points on web map tiles."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = hvplot.sampledata.earthquakes(\"pandas\")\n",
    "\n",
    "df.hvplot.points(\n",
    "    x=\"lon\", y=\"lat\", c=\"mag\", s=\"depth\", cmap=\"inferno_r\",\n",
    "    clabel=\"Magnitude values\", title=\"Earthquake depth (color by magnitude)\",\n",
    "    geo=True, tiles=True,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Geographic plot with GeoPandas"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import geopandas as gpd\n",
    "import hvplot.pandas  # noqa\n",
    "\n",
    "data = {\n",
    "    'City': ['London', 'Paris', 'Berlin', 'Madrid', 'Rome', 'Vienna', 'Warsaw', 'Amsterdam'],\n",
    "    'Country': ['United Kingdom', 'France', 'Germany', 'Spain', 'Italy', 'Austria', 'Poland', 'Netherlands'],\n",
    "    'Latitude': [51.5074, 48.8566, 52.5200, 40.4168, 41.9028, 48.2082, 52.2297, 52.3676],\n",
    "    'Longitude': [-0.1278, 2.3522, 13.4050, -3.7038, 12.4964, 16.3738, 21.0122, 4.9041]\n",
    "}\n",
    "cities = gpd.GeoDataFrame(\n",
    "    data,\n",
    "    geometry=gpd.points_from_xy(data['Longitude'], data['Latitude']),\n",
    "    crs=\"EPSG:4326\",\n",
    ")\n",
    "\n",
    "cities.hvplot.points(geo=True, tiles=True)"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
